@tycoworks/tycoslide 0.15.1 → 0.16.0

package/README.md

@@ -1,10 +1,10 @@
 # tycoslide
 
-Create editable, on-brand PowerPoint slides from markdown, using your existing .pptx templates.
+Create editable PowerPoint slides from markdown, using your existing .pptx templates.
 
 ## Getting started
 
-1. **Create a tycoslide theme.** Install the [create-theme](skills/create-theme) skill (`npx skills add tycoworks/tycoslide`) and give an agent such as Claude Code or Codex your `.pptx`. You'll get back an npm package of mapped layouts, colors, and visual assets, like the [tycoworks-theme](https://github.com/tycoworks/tycoworks-theme).
+1. **Create a tycoslide theme.** Install the [create-theme](skills/create-theme) skill (`npx skills add tycoworks/tycoslide --skill create-theme`) and give an agent such as Claude Code or Codex your `.pptx`. You'll get back an npm package of mapped layouts, colors, and visual assets, like the [tycoworks-theme](https://github.com/tycoworks/tycoworks-theme).
 2. **Write slides in markdown.** GitHub-flavored markdown is supported; see [Markdown support](#markdown-support) below. tycoslide themes also include an agent skill, so an agent can write the slides for you.
 3. **Build.** `npx tycoslide build deck.md` compiles the markdown into an editable PowerPoint file.
 
@@ -18,17 +18,21 @@ npm install
 npx tycoslide build how-it-works.md
 ```
 
+https://github.com/user-attachments/assets/f31c11d8-3fe6-464f-8f02-56645b4ce3a6
+
 ## Markdown support
 
 - Paragraphs, bullets and numbered lists, with bold, italic and links
-- Tables
+- Tables, images and speaker notes
 - Code, with [Shiki](https://shiki.style) syntax highlighting
 - [Mermaid](https://mermaid.js.org) diagrams
-- Images, from the theme's asset catalog or a file path
-- Speaker notes
 
-Full syntax in [syntax.md](theme-package/syntax.md).
+Full syntax in [markdown.md](docs/markdown.md).
 
 ## Requirements
 
 Node 23.6 or later. Mermaid diagrams need Chrome on the machine; tycoslide finds an installed one, or run `npx playwright install chromium-headless-shell`.
+
+## Thanks
+
+tycoslide was inspired by [pptx-automizer](https://github.com/singerla/pptx-automizer), which it uses under the hood, and by [Slidev](https://sli.dev) and its markdown slides.

package/dist/agents/catalog.d.ts

@@ -0,0 +1,32 @@
+import * as z from "zod";
+/**
+ * One image a theme offers deck authors. `fit` is the value an author copies
+ * into the image's title, so it is already a title value.
+ */
+declare const AssetEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    fit: z.ZodEnum<{
+        readonly Contain: "contain";
+        readonly Cover: "cover";
+        readonly ScaleDown: "scale-down";
+    }>;
+    description: z.ZodString;
+}, z.core.$strict>;
+declare const AssetCatalogSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    fit: z.ZodEnum<{
+        readonly Contain: "contain";
+        readonly Cover: "cover";
+        readonly ScaleDown: "scale-down";
+    }>;
+    description: z.ZodString;
+}, z.core.$strict>>>;
+export type AssetEntry = z.infer<typeof AssetEntrySchema>;
+export type AssetCatalog = z.infer<typeof AssetCatalogSchema>;
+/**
+ * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
+ * agent searches, copies images from, and takes each image's fit from. It is
+ * authored with the theme and required; a theme with no images has `{}`.
+ */
+export declare function loadAssetCatalog(themeDir: string): AssetCatalog;
+export {};

package/dist/agents/catalog.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as z from "zod";
+import { ImageFit, strict } from "../index.js";
+import { ASSETS_FILE } from "./files.js";
+/**
+ * One image a theme offers deck authors. `fit` is the value an author copies
+ * into the image's title, so it is already a title value.
+ */
+const AssetEntrySchema = strict({
+    path: z.string(),
+    fit: z.enum(ImageFit),
+    description: z.string(),
+});
+// `{ category: { name: entry } }`. Both record levels are open (the names are the
+// theme's own); only the entry is strict.
+const AssetCatalogSchema = z.record(z.string(), z.record(z.string(), AssetEntrySchema));
+/**
+ * Read and validate a theme's image catalog, `assets.json`: what a deck-writing
+ * agent searches, copies images from, and takes each image's fit from. It is
+ * authored with the theme and required; a theme with no images has `{}`.
+ */
+export function loadAssetCatalog(themeDir) {
+    const path = join(themeDir, ASSETS_FILE);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        throw new Error(`Image catalog not found or invalid JSON: ${path}`);
+    }
+    const result = AssetCatalogSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`${ASSETS_FILE}: invalid image catalog\n${z.prettifyError(result.error)}`);
+    }
+    return result.data;
+}

package/dist/agents/commands.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+/** The installed tycoslide package: where its shipped files live, and what a skill pins. */
+export type ToolPackage = {
+    root: string;
+    name: string;
+    version: string;
+};
+/** Register the agent layer's commands on the CLI program. */
+export declare function registerAgentCommands(program: Command, tool: ToolPackage): void;

package/dist/agents/commands.js

@@ -0,0 +1,57 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, posix, resolve } from "node:path";
+import { loadThemeConfig } from "../index.js";
+import { loadAssetCatalog } from "./catalog.js";
+import { extractTemplate, summarizeExtraction } from "./extract.js";
+import { ASSETS_DIR, ASSETS_FILE, MANIFEST_FILE, PACKAGE_JSON, SKILL_FILE, SKILL_ZIP_EXT, TEMPLATE_FILE, THEME_CONFIG, THEME_PACKAGE_DIR, } from "./files.js";
+import { generateManifest } from "./manifest.js";
+import { renameSkill, skillPackageJson, zipDir } from "./skill.js";
+/** The CLI's line for something written, with an optional note on what it holds. */
+function wrote(target, detail) {
+    console.log(detail ? `WROTE ${target}  ${detail}` : `WROTE ${target}`);
+}
+/** Register the agent layer's commands on the CLI program. */
+export function registerAgentCommands(program, tool) {
+    const skillMdPath = resolve(tool.root, THEME_PACKAGE_DIR, SKILL_FILE);
+    program
+        .command("package")
+        .description("Zip the theme into an Agent Skill for AI agents")
+        .option(`-c, --config <path>`, "path to theme config file", THEME_CONFIG)
+        .action(async (opts) => {
+        const config = loadThemeConfig(resolve(process.cwd(), opts.config));
+        const catalog = loadAssetCatalog(config.rootDir);
+        const themePkg = JSON.parse(readFileSync(resolve(process.cwd(), PACKAGE_JSON), "utf-8"));
+        if (!themePkg.name) {
+            throw new Error(`Cannot name the skill: the theme's ${PACKAGE_JSON} has no "name" field.`);
+        }
+        // basename drops any npm scope, e.g. "@acme/acme-slides" -> "acme-slides".
+        const skillName = basename(themePkg.name);
+        let skillMd;
+        try {
+            skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
+        }
+        catch (err) {
+            throw new Error(`${skillMdPath}: ${err.message}`);
+        }
+        // Bundle the WHOLE theme so the skill is self-contained: unzip ->
+        // `npm install` (pulls the engine, its docs and its deps) -> `npx tycoslide build`.
+        const generated = {
+            [PACKAGE_JSON]: skillPackageJson(themePkg, tool),
+            [SKILL_FILE]: skillMd,
+            [MANIFEST_FILE]: generateManifest(config),
+        };
+        const zipFile = `${skillName}${SKILL_ZIP_EXT}`;
+        const zip = await zipDir(process.cwd(), skillName, config, catalog, [opts.config, ASSETS_FILE], generated);
+        writeFileSync(resolve(process.cwd(), zipFile), zip);
+        wrote(zipFile);
+    });
+    program
+        .command("extract")
+        .description(`Read a template for a theme: write ${TEMPLATE_FILE}, and copy its images into ${ASSETS_DIR}/`)
+        .argument("<template>", "path to the .pptx template")
+        .action(async (template) => {
+        const summary = summarizeExtraction(await extractTemplate(resolve(process.cwd(), template), process.cwd()));
+        wrote(TEMPLATE_FILE, summary.template);
+        wrote(ASSETS_DIR + posix.sep, summary.images);
+    });
+}

package/dist/agents/extract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract: read a template for a theme in one pass. Writes the inventory, with the
+ * images it copied, to `template.json`, and copies the template's images into
+ * `assets/`, both in the theme folder.
+ */
+import { type Inventory } from "./inventory.js";
+import { type MediaImage } from "./media.js";
+export type TemplateImage = MediaImage & {
+    /** Where the image is in the theme folder; for a duplicate, the copy that was kept. Absent when missing. */
+    path?: string;
+};
+/** The contents of `template.json`. */
+export type TemplateFacts = Inventory & {
+    images: TemplateImage[];
+};
+/** Read `templatePath`, write `template.json` and copy the images into `themeDir`. */
+export declare function extractTemplate(templatePath: string, themeDir: string): Promise<TemplateFacts>;
+/** What was written, in a phrase each: the template's facts, and the images. */
+export declare function summarizeExtraction(facts: TemplateFacts): {
+    template: string;
+    images: string;
+};

package/dist/agents/extract.js

@@ -0,0 +1,54 @@
+/**
+ * Extract: read a template for a theme in one pass. Writes the inventory, with the
+ * images it copied, to `template.json`, and copies the template's images into
+ * `assets/`, both in the theme folder.
+ */
+import { writeFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { ASSETS_DIR, jsonFile, TEMPLATE_FILE } from "./files.js";
+import { readInventory } from "./inventory.js";
+import { copyImages, MediaOutcome } from "./media.js";
+import { Presentation } from "./pptx.js";
+/** Read `templatePath`, write `template.json` and copy the images into `themeDir`. */
+export async function extractTemplate(templatePath, themeDir) {
+    const presentation = await Presentation.open(templatePath);
+    const inventory = await readInventory(presentation);
+    const images = await copyImages(presentation, join(themeDir, ASSETS_DIR));
+    const facts = {
+        ...inventory,
+        images: images.map((image) => {
+            const kept = image.outcome === MediaOutcome.Missing ? undefined : (image.duplicateOf ?? image.file);
+            return kept ? { ...image, path: posix.join(ASSETS_DIR, kept) } : image;
+        }),
+    };
+    writeFileSync(join(themeDir, TEMPLATE_FILE), jsonFile(facts));
+    return facts;
+}
+/** What was written, in a phrase each: the template's facts, and the images. */
+export function summarizeExtraction(facts) {
+    const count = (outcome) => facts.images.filter((image) => image.outcome === outcome).length;
+    const template = [
+        counted(facts.slides.length, "slide"),
+        counted(facts.duplicates.length, "duplicate group"),
+        counted(facts.embeddedFonts.length, "embedded typeface"),
+    ];
+    // [count, noun, what happened, report even when none]
+    const images = [
+        [count(MediaOutcome.Copied), "image", "copied", true],
+        [count(MediaOutcome.Present), "image", "already present", false],
+        [count(MediaOutcome.Duplicate), "identical image", "skipped", false],
+        [count(MediaOutcome.Missing), "image", "missing from the template", false],
+    ];
+    return {
+        template: template.join(LIST_SEPARATOR),
+        images: images
+            .filter(([n, , , always]) => always || n > 0)
+            .map(([n, noun, state]) => `${counted(n, noun)} ${state}`)
+            .join(LIST_SEPARATOR),
+    };
+}
+const LIST_SEPARATOR = ", ";
+/** `1 slide`, `3 slides`. */
+function counted(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}

package/dist/{files.d.ts → agents/files.d.ts}

@@ -11,13 +11,23 @@ export declare const ASSETS_FILE = "assets.json";
 /**
  * The one archive a packaged theme's declared assets ship inside. Entries are
  * stored at theme-relative POSIX paths and never rewritten: packaging writes
- * them, building expands them. Zip format, deliberately NOT named .zip: the
+ * them, and an agent unzips them. Zip format, deliberately NOT named .zip: the
  * upload host rejects nested .zip entries by extension while accepting .pptx,
  * which is also a zip -- so the archive travels under a neutral name.
  */
 export declare const ASSETS_ARCHIVE = "assets.dat";
 export declare const SKILL_FILE = "SKILL.md";
-export declare const SYNTAX_FILE = "syntax.md";
 export declare const THEME_PACKAGE_DIR = "theme-package";
-/** The manifest a packaged skill installs from, authored rather than copied. */
+/**
+ * npm's package manifest: the theme's, which names the skill, and the packaged
+ * skill's own, which it installs from (authored rather than copied).
+ */
 export declare const PACKAGE_JSON = "package.json";
+/** The packaged skill is one zip, named `<skill name>.zip`. */
+export declare const SKILL_ZIP_EXT = ".zip";
+/** What `tycoslide extract` learns about a template, written in the theme folder. */
+export declare const TEMPLATE_FILE = "template.json";
+/** Where a theme keeps its images, and where `tycoslide extract` copies a template's. */
+export declare const ASSETS_DIR = "assets";
+/** `value` as the contents of a JSON file the agent layer writes: indented, with a final newline. */
+export declare function jsonFile(value: unknown): string;

package/dist/{files.js → agents/files.js}

@@ -11,7 +11,7 @@ export const ASSETS_FILE = "assets.json";
 /**
  * The one archive a packaged theme's declared assets ship inside. Entries are
  * stored at theme-relative POSIX paths and never rewritten: packaging writes
- * them, building expands them. Zip format, deliberately NOT named .zip: the
+ * them, and an agent unzips them. Zip format, deliberately NOT named .zip: the
  * upload host rejects nested .zip entries by extension while accepting .pptx,
  * which is also a zip -- so the archive travels under a neutral name.
  */
@@ -20,9 +20,22 @@ export const ASSETS_ARCHIVE = "assets.dat";
 // the root of a skill folder, and a case-sensitive filesystem will not find any
 // other.
 export const SKILL_FILE = "SKILL.md";
-export const SYNTAX_FILE = "syntax.md";
 // The folder holding the SKILL.md template copied into each packaged theme, kept
 // out of the repo root so skill installers do not mistake it for this repo's own skill.
 export const THEME_PACKAGE_DIR = "theme-package";
-/** The manifest a packaged skill installs from, authored rather than copied. */
+/**
+ * npm's package manifest: the theme's, which names the skill, and the packaged
+ * skill's own, which it installs from (authored rather than copied).
+ */
 export const PACKAGE_JSON = "package.json";
+/** The packaged skill is one zip, named `<skill name>.zip`. */
+export const SKILL_ZIP_EXT = ".zip";
+/** What `tycoslide extract` learns about a template, written in the theme folder. */
+export const TEMPLATE_FILE = "template.json";
+/** Where a theme keeps its images, and where `tycoslide extract` copies a template's. */
+export const ASSETS_DIR = "assets";
+const JSON_INDENT = 2;
+/** `value` as the contents of a JSON file the agent layer writes: indented, with a final newline. */
+export function jsonFile(value) {
+    return `${JSON.stringify(value, null, JSON_INDENT)}\n`;
+}

package/dist/agents/inventory.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Inventory: what a template holds, in the terms `theme.json` needs. The slide
+ * size, the colour and font schemes, the embedded typefaces; each slide's
+ * position, layout, background tone and shapes (with frames in EMU, as
+ * `theme.json` takes them); and which slides share the same geometry.
+ */
+import { type Frame } from "../index.js";
+import { type Presentation } from "./pptx.js";
+/** The twelve colour-scheme slots, in the order PowerPoint lists them. */
+export declare const SCHEME_SLOTS: readonly ["dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"];
+type SchemeSlot = (typeof SCHEME_SLOTS)[number];
+/** A background's tone, as a layout's `variant` would describe it; `image` for a picture fill. */
+export declare const Background: {
+    readonly Light: "light";
+    readonly Dark: "dark";
+    readonly Image: "image";
+    readonly Unknown: "unknown";
+};
+export type Background = (typeof Background)[keyof typeof Background];
+/** Scheme slot → `#RRGGBB`. */
+type SchemeColors = Partial<Record<SchemeSlot, string>>;
+export type ColorScheme = {
+    name: string;
+} & SchemeColors;
+export type FontScheme = {
+    name: string;
+    major?: string;
+    minor?: string;
+};
+/** A shape's kind. A fillable shape's kind is the `theme.json` block type that fills it. */
+export declare const ShapeKind: {
+    readonly Text: "text";
+    readonly Image: "image";
+    readonly Table: "table";
+    readonly Group: "group";
+    readonly Other: "other";
+};
+export type ShapeKind = (typeof ShapeKind)[keyof typeof ShapeKind];
+/** Where a placeholder that doesn't position itself takes its frame from. */
+export declare const FrameSource: {
+    readonly Layout: "layout";
+    readonly Master: "master";
+};
+export type FrameSource = (typeof FrameSource)[keyof typeof FrameSource];
+export type InventoryShape = {
+    /** The shape's name; a group's members are prefixed with the group's name and `/`. */
+    name: string;
+    kind: ShapeKind;
+    /** In EMU, as `theme.json` takes it. */
+    frame?: Frame;
+    frameFrom?: FrameSource;
+    rows?: number;
+    cols?: number;
+    /**
+     * The start of the shape's text, with `¶` between paragraphs and `↵` for line
+     * breaks: where a parameter template puts `\n`.
+     */
+    text: string;
+};
+export type InventorySlide = {
+    /** The number in the part name, `ppt/slides/slideN.xml`: what `theme.json`'s `slideNumber` means. */
+    slide: number;
+    /** 1-based position in presentation order (how rendered previews are numbered); absent when not shown. */
+    position?: number;
+    layout?: string;
+    background: Background;
+    shapes: InventoryShape[];
+};
+export type Inventory = {
+    slideSize: {
+        cx: number;
+        cy: number;
+    };
+    colorScheme: ColorScheme;
+    fontScheme: FontScheme;
+    embeddedFonts: string[];
+    slides: InventorySlide[];
+    /** Groups of slide numbers whose shapes have the same kinds and frames, to within a point. */
+    duplicates: number[][];
+};
+/** Read a template's inventory. */
+export declare function readInventory(presentation: Presentation): Promise<Inventory>;
+export {};